feat(patrol): add patrolling module by paul-nechifor · Pull Request #1488 · dimensionalOS/dimos

paul-nechifor · 2026-03-08T01:56:55Z

Problem

We need a way to patrol explored areas.

Closes DIM-659

Solution

Wrote a few patrolling algorithms, and I'm using coverage by default because it looks the best.
Wrote a test to visualize how well it covers the space (all tests are on the Hong Kong office scan from Ivan).:

coverage	frontier	random

Tested the best values for saturation_threshold and clearance_radius_m.

Tested the best values for candidates_to_consider.

Verified that the robot patrols for a significant while.

Breaking Changes

None.

How to Test

uv run dimos run --disable spatial-memory unitree-go2-agentic

and tell it to start patrolling.

Issues

This doesn't always work because you get bad detections such as this (that's actually part of the chair):

It messes up the entire flow. We need persistent 3D detections, and maybe a 360 camera.

Contributor License Agreement

I have read and approved the CLA.

greptile-apps · 2026-03-08T02:03:34Z

Greptile Summary

This PR introduces a complete patrolling module for the Dimensional OS robot stack, enabling autonomous area patrol via three interchangeable routing strategies (coverage, frontier, random). It wires cleanly into the existing Module / autoconnect framework and is backed by A*-based path planning, Voronoi-weighted candidate sampling, and a bounded-memory visitation history.

Key findings:

Missing default case in create_patrol_router — the match statement lacks a case _: branch; an unrecognized router name silently returns None, violating the PatrolRouter return type and causing a downstream AttributeError.
Redundant duplicate import of PoseStamped in utilities.py (line 16-17, second shadows the first).

The core patrolling logic is well-structured, thread-safe, and backed by tests. These two issues are straightforward to fix and should be addressed before merge.

Confidence Score: 4/5

Safe to merge after addressing the missing default case in the factory function, which currently allows implicit None returns that violate the type annotation.
The patrolling module is well-structured with sound core logic and proper threading. The identified issues are straightforward to fix: a missing default case in the factory function (type violation) and a redundant import. The former must be addressed; the latter is minor cleanup. The behavioral change to min_cost_astar is intentional per the PR summary and does not require further action. The core patrolling, routing, and A* logic are robust and well-tested.
dimos/navigation/patrolling/create_patrol_router.py (missing default case—must be fixed before merge)

Sequence Diagram

sequenceDiagram
    participant Agent as AI Agent / Skill
    participant PM as PatrollingModule
    participant Router as PatrolRouter (Coverage/Frontier/Random)
    participant Nav as NavigationSystem
    participant ROS as ROS Topics (odom / costmap / goal_reached)

    Agent->>PM: start_patrol()
    PM->>PM: spawn _patrol_thread

    loop Patrol Loop
        PM->>Router: next_goal()
        Router->>Router: sample unvisited safe cells (Voronoi-weighted)
        Router->>Router: run min_cost_astar for each candidate
        Router-->>PM: PoseStamped goal (or None)

        alt goal is None
            PM->>PM: wait 2s or stop_event
        else goal available
            PM->>Nav: goal_request.publish(goal)
            PM->>PM: _goal_or_stop_event.wait()
            Nav-->>ROS: robot navigates
            ROS-->>PM: goal_reached callback
            PM->>PM: _goal_or_stop_event.set()
        end
    end

    ROS-->>PM: odom callback → _latest_pose, Router.handle_odom()
    ROS-->>PM: global_costmap callback → Router.handle_occupancy_grid() (throttled 60s)
    Router->>Router: VisitationHistory.update_grid() + _rebuild()

    Agent->>PM: stop_patrol()
    PM->>PM: _stop_event.set(), _goal_or_stop_event.set()
    PM->>Nav: goal_request.publish(_latest_pose)  [cancel navigation]
    PM->>PM: _patrol_thread.join()

_{Last reviewed commit: 1eec5e0}

dimos/navigation/patrolling/create_patrol_router.py

dimos/navigation/patrolling/utilities.py

leshy · 2026-03-13T03:23:34Z

I'd maybe add some of those nice pictures + a short description on how it works, into docs somewhere? docs/capabilities ?

leshy · 2026-03-13T15:22:28Z

dimos/agents/skills/person_follow.py


        Args:
            query: Description of the person to follow (e.g., "man with blue shirt")
+            initial_bbox: Optional pre-computed bounding box [x1, y1, x2, y2].


this is exactly what Detection2d/bbox model is, should we use those for detections to follow?

I can imagine visual following making sense in many cases, would be good to support standard detection types?

person_follow.py does support navigating by Detection3D, but it's not the default. Following by EdgeTAM detections works well enough in practice. With Detection3D the distance isn't estimated in all situations, for example if a person is detected in the distance, but no voxels have been detected there yet. Visual servoing works quite nice from close-up (feet only detections) to far away detections.

But this is probably not related to this PR so maybe it should be discussed further on an issue.

leshy · 2026-03-13T15:25:40Z

dimos/navigation/patrolling/module.py

+
+
+class PatrollingModule(Module):
+    odom: In[PoseStamped]


why not use self.tf?

Because tf does not have subscribe. You always have to request it.

leshy · 2026-03-13T15:27:57Z

dimos/navigation/patrolling/module.py

+class PatrollingModule(Module):
+    odom: In[PoseStamped]
+    global_costmap: In[OccupancyGrid]
+    goal_reached: In[Bool]


this might be a good situation for jeffs RPC in which we feed nav module directly to this module as a dependancy, so it can call rpcs from it? we get nice type level dependance right? I haven't done this yet so slightly unsure

I've used Jeff's RPC in multiple places, including this PR, but I don't think it makes sense here. In this case, I want the navigation module to notify me when the goal has been reached (or declared a failure). I can't do that via RPC.

leshy · 2026-03-13T15:32:05Z

dimos/navigation/patrolling/module.py

+        with self._patrol_lock:
+            if self._patrol_thread is not None and self._patrol_thread.is_alive():
+                return "Patrol is already running. Use `stop_patrol` to stop."
+            self._planner_spec.set_replanning_enabled(False)


How come? don't we have dynamic env issue if we disable replanning?

In normal navigation, when you set a goal, you need to get there. With patrolling, what's important is covering the patrol area, not necessarily getting to a specific point.

When setting a specific random target, there are issues that cause re-planning every once in a while (maybe someone got in the way, maybe some random noise blocked the path, maybe the goal was unreachable to begin with).

Instead of re-planning to get to the arbitrary target, it's a lot faster to just select another arbitrary target. If the goal is unreachable, the robot wastes a lot of time trying to get to a place that it cannot get to.

The router is in charge of making sure enough of the area is covered, so if the goal was actually important to get to, it will try to get there soon enough.

greptile-apps bot reviewed Mar 8, 2026

View reviewed changes

dimos/navigation/patrolling/create_patrol_router.py Show resolved Hide resolved

dimos/navigation/patrolling/utilities.py Show resolved Hide resolved

paul-nechifor force-pushed the paul/feat/perceive-loop branch from 649db7b to 0e07984 Compare March 9, 2026 11:39

paul-nechifor force-pushed the paul/feat/patrol branch from 7dc71ae to a123517 Compare March 9, 2026 12:17

paul-nechifor force-pushed the paul/feat/perceive-loop branch 2 times, most recently from ea7a704 to dfb30a0 Compare March 9, 2026 22:40

paul-nechifor force-pushed the paul/feat/patrol branch 3 times, most recently from a4a61aa to 7c4e027 Compare March 10, 2026 06:33

paul-nechifor changed the base branch from paul/feat/perceive-loop to dev March 10, 2026 06:34

spomichter changed the base branch from dev to main March 10, 2026 08:45

spomichter changed the base branch from main to dev March 10, 2026 08:45

spomichter force-pushed the paul/feat/patrol branch 2 times, most recently from 1bd23c3 to 0182ab6 Compare March 10, 2026 09:00

paul-nechifor force-pushed the paul/feat/patrol branch 2 times, most recently from bd956c9 to 716415d Compare March 11, 2026 23:13

leshy reviewed Mar 13, 2026

View reviewed changes

paul-nechifor added 6 commits March 15, 2026 01:25

feat(patrol): add patrolling module

2b371cc

integrate patrol and perception

b343665

nerf speed

81b6563

use proper image

5339796

mypy

e43291c

fixes

d5e1d48

paul-nechifor force-pushed the paul/feat/patrol branch from 716415d to d5e1d48 Compare March 14, 2026 23:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(patrol): add patrolling module#1488

feat(patrol): add patrolling module#1488
paul-nechifor wants to merge 6 commits intodevfrom
paul/feat/patrol

paul-nechifor commented Mar 8, 2026 •

edited

Loading

Uh oh!

greptile-apps bot commented Mar 8, 2026

Uh oh!

Uh oh!

Uh oh!

leshy commented Mar 13, 2026

Uh oh!

leshy Mar 13, 2026

Uh oh!

paul-nechifor Mar 14, 2026

Uh oh!

leshy Mar 13, 2026

Uh oh!

paul-nechifor Mar 14, 2026

Uh oh!

leshy Mar 13, 2026 •

edited

Loading

Uh oh!

paul-nechifor Mar 14, 2026

Uh oh!

leshy Mar 13, 2026

Uh oh!

paul-nechifor Mar 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

paul-nechifor commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Breaking Changes

How to Test

Issues

Contributor License Agreement

Uh oh!

greptile-apps bot commented Mar 8, 2026

Greptile Summary

Confidence Score: 4/5

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

leshy commented Mar 13, 2026

Uh oh!

leshy Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

paul-nechifor Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

leshy Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

paul-nechifor Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

leshy Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paul-nechifor Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

leshy Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

paul-nechifor Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

paul-nechifor commented Mar 8, 2026 •

edited

Loading

leshy Mar 13, 2026 •

edited

Loading

paul-nechifor Mar 13, 2026 •

edited

Loading